In avisserquinn/AHgenPackage:

knitr::opts_chunk$set(echo = TRUE, 
                      cache = TRUE, 
                      message=FALSE, 
                      warning=FALSE)

library(knitr)
library(tidyverse)
library(igraph)
library(AHgenPackage)

htmltools::img(src = knitr::image_uri(normalizePath(file.path("images/hex.png"))), 
               alt = 'logo', 
               style = 'position:absolute; top:0; right:0; padding:10px; max-width:20%')

This first vignette is all about data in AHgen:

Section 1 - Data types
Section 2 - Read in data using the read_* functions
Section 3 - Convert to different data types using the conversion family of functions
Section 4 - Navigating the data using the tidyverse and igraph packages

You can navigate, or jump to a specific section, using the buttons on the left.

1. Data types

1.1 Adjacency matrix

@Melissa

1.2 Edge list

@Melissa

1.3 igraph

An igraph is an object class from the package of the same name. The igraph data type is a special way of formatting complex networks, enabling the creation of large networks and speedy application of network analysis.

The code output below is an igraph of an abstraction hierarchy.

file <- system.file("extdata", "AH_mobility.xlsx", package = "AHgenPackage")
dh <- read_adjMat(file) 
di <- dh %>% adjMat_to_igraph(vInfo = dh %>% select(1:3))
di

The first line states that this is an igraph. It also provides a codename for the graph, UNW-:

U The graph is Undirected
N The vertices have Names
W The Weight attribute has been set
- The graph is not bipartite

The second line provides the attributes of the vertices (denoted as v) and edges (denoted as e):

name (v/c) The vertices are named, and have the class c, character
level (v/n) The vertices have an attribute called level, with the class n, numeric
levelName (v/c) The vertices have an attribute called levelName, with the class c, character
weight (e/n) The edges have a weight, with the class n, numeric
layer (e/c) The edges have an attribute called layer, with the class c, character

The remainder of the output represents the edges and the vertex names.

2. Read data

The read in functions in AHgen are prefixed with read.

ls("package:AHgenPackage", pattern = "read")

Here we focus on the two functions, read_adjMat() and read_vInfo(), which read in the main inputs to AHgen:

An adjacency matrix capturing the links between the levels of the abstraction hierarchy
Vertex information, the level and level name associated with each vertex

These inputs should be:

In the .xlsx format, i.e. an Excel spreadsheet.
Placed in the inputs folder.

2.1 Adjacency matrix

The adjacency matrix can be read in using the function read_adjMat(). This function has three input arguments:

filename The file path (relative to the AHgen folder)
sheet The sheet number of the adjacency matrix; this is set to 1 by default
rescale Whether the edge weightings in the adjacency matrix should be rescaled to 0.5; this is set to FALSE by default

Note, two of the three read_adjMat() input arguments have default values. If only the filename is provided, these arguments will take this default value.

Click below to explore two example applications.

Show code - Example 1

The classic human factors example of cooking food in a microwave. The Excel file, AH_microwave.xlsx is provided in the inputs folder. An annotated exert of the adjacency matrix is shown below.

Add image here.

The column of vertex names must be named vName
Vertex names run left to right
And top to bottom
The links between vertices are denoted by 1. Non-links are denoted by empty cells. Note, zeroes can also be used to indicate non-links
The diagonal cannot be linked, a vertex cannot link to itself
This workbook has two sheets, the adjacency matrix, sheet 1, and the vertex information, sheet 2

Point 6 highlighted that there are two sheets, but we know from above that read_adjMat() reads in sheet 1 by default. Thus, these first two code chunks provide identical outputs.

file <- system.file("extdata", "AH_microwave.xlsx", package = "AHgenPackage")
file
read_adjMat(file)
read_adjMat(file, sheet = 1)

Notice that the empty cells from the Excel file are filled with zeroes by AHgen. This means these vertices are not linked, i.e. they have no weight. We might want to rescale the linked, or weighted edges, to 0.5. To do this, change the rescale argument to TRUE.

read_adjMat(file, rescale = TRUE)

Show code - Example 2

We now consider a second example abstraction hierarchy, AH_mobility.xlsx, which is also available in the inputs folder.

Add image here.

As before, the column of vertex names is called vName
And the vertex names run left to right
And top to bottom
The links between vertices are again denoted by 1. This time, non-links are denoted by 0 cells
These is only one sheet in this workbook
But there are two extra columns of vertex information, level and levelName. If these columns had different names they would be read in as vertices!

With only one sheet, the first sheet is the adjacency matrix, and if we don't want to rescale the data, then only one input argument is required "inputs/AH_mobility.xlsx".

#### read_adjMat("inputs/AH_mobility.xlsx")

The code chunk below shows what happens if there is a mismatch in column names. Check out the file AH_mobility_error.xlsx to see if you can spot the problem.

#### read_adjMat("inputs/AH_mobility_error.xlsx")

2.2 Vertex information

The vertex information can be read in using the function read_vInfo(). This function has two input arguments:

filename The file path (relative to the AHgen folder)
sheet The sheet number of the vertex information. This is set to 1 by default

Show code - Example 3

For the microwave AH, the vertex information is in the second sheet. Each row describes a single vertex in terms of level, level name and vertex name. To avoid errors, these columns must be named level, levelName and vName.

Add image here.

read_vInfo(file, sheet = 2)

Show code - Example 4

We saw in Example 2 that the vertex information was embedded in the adjacency matrix. This can be extracted using the tidyverse select function.

#### read_adjMat("inputs/AH_mobility.xlsx") %>% select(level, levelName, vName)

3. Conversions

In AHgen, the abstraction hierarchy can be captured in three different formats:

Adjacency matrix
Edge list
igraph

To change format, AHgen has a family of six conversion functions:

adjMat_to_edgelist() and adjMat_to_igraph(), where the input arguments are the adjacency matrix
edgelist_to_igraph() and edgelist_to_adjMat(), where the input arguments are the abstraction hierarchy in edge list format, and the vertex information
igraph_to_adjMat() and igraph_to_edgelist(), where the input arguments are the abstraction hierarchy in the igraph format

Before introducing the examples, we need to save the adjacency matrix and vertex information as objects in the environment. We do this using the <- operator.

file <- system.file("extdata", "AH_mobility.xlsx", package = "AHgenPackage")
file
dh <- read_adjMat(file) 
dv <- dh %>% select(level, levelName, vName)

Show code - Example 5 - From adjacency matrix

de <- dh %>% adjMat_to_edgelist(vInfo = dv); de
di <- dh %>% adjMat_to_igraph(vInfo = dv); di

Show code - Example 6 - From edge list

Note that, when converting from an edge list, we need to specify the vertex information.

de %>% edgelist_to_igraph(vInfo = dv)
de %>% edgelist_to_adjMat(vInfo = dv)

Show code - Example 7 - From igraph

di %>% igraph_to_adjMat
di %>% igraph_to_edgelist

Paused here

4. Navigating the data

Now let's consider how to navigate and explore these three data types.

The adjacency matrix and edge list are in a tibble format, an easy to read tabular form. They can be navigated like any data.frame or tibble in R using functions such as select() and filter()
The igraph is a special way of formatting complex networks. The package of the same name introduces a number of functions to interrogate the network

Click below for examples for each data type.

Show code - Example 8 - Adjacency matrix

# Select vertices by name
dh %>% select(`Provide efficient and accessible mobility`)

# Select vertices which match a pattern
dh %>% select(vName, contains("safe"))

# Filter to a specific vertex
dh %>% filter(vName == "Compliant user behaviour")

# Filter to vertices matching a pattern
dh %>% filter(str_detect(vName, "capab|Capab"))

Show code - Example 9 - Edge list

# Filter for edges in a specific layer
de %>% filter(layer == "l1FP_l2VPM")

# Filter for edges linking vertices containing road
de %>% filter_all(any_vars(str_detect(str_to_lower(.), "road")))

# Filter for edges linking from the vertex "Vehicle capacity"
de %>% filter(from == "Vehicle capacity")

Show code - Example 10 - igraph

# Extract vertices
V(di)

# Extract edges
E(di)

# Extract vertex attribute name
V(di)$name

# Extract vertex attribute level
V(di)$level

# Extract vertex attribute levelName
V(di)$levelName

# Extract edge attribute weight
E(di)$weight

# Extract edge attribute layer
E(di)$layer